Addressed several logical issues found during code review:

1. Fixed environment variable name: Changed from HUGGING_FACE_HUB_TOKEN
   to the correct HF_TOKEN as per huggingface_hub documentation

2. Removed unused 'hardware' variable in _create_readme method

3. Improved SpaceStage status mapping to handle all possible states:
   - Added support for RUNNING_BUILDING, BUILD_ERROR, RUNTIME_ERROR
   - Added support for CONFIG_ERROR, NO_APP_FILE, DELETING
   - Better categorization of error vs pending states

4. Fixed Dockerfile environment variable escaping to properly handle
   backslashes followed by quotes

5. Added safety check for empty deployment names in _sanitize_space_name
   to prevent edge case failures

6. Fixed potential None access in log error message by checking if
   space_url exists before using it

These fixes ensure more robust error handling and better compatibility
with the Huggingface Spaces API.

Removed over-engineered code to make it minimal and maintainable:

- Removed HuggingfaceDeploymentMetadata class, use simple dict instead
- Removed _sanitize_space_name complexity, simplified to basic regex
- Inlined _create_readme and _create_dockerfile methods
- Simplified status mapping from 10+ cases to 3 simple cases
- Removed unnecessary exception wrapping and verbose logging
- Removed unused imports and helper methods

The code is now ~200 lines instead of ~500 lines, much easier to
understand and maintain while keeping all core functionality.

Fixed several bugs found during code review:

1. CRITICAL: Fixed Dockerfile env var escaping - values with quotes or
   backslashes would break the Dockerfile. Now properly escapes both.

2. Fixed empty space name handling - if deployment name only contains
   special characters, now defaults to 'deployment' instead of empty string

3. Added try/except around hardware and storage API calls to prevent
   them from crashing the entire provisioning if they fail

4. Changed flavor name from 'huggingface' to 'huggingface-spaces' to
   avoid confusion with the existing model deployer flavor

These fixes make the deployer more robust and handle edge cases properly.

The flavor name should be 'huggingface' not 'huggingface-spaces'.
Model deployer and deployer are different component types so there's
no naming collision.

Fixed all linting issues found by scripts/lint.sh and scripts/docstring.sh:

1. F821 - Added HfApi to TYPE_CHECKING imports to fix undefined name error
2. DAR302 - Removed 'Yields' section from do_get_deployment_state_logs
   since it only raises an exception
3. DAR401 - Added Exception to Raises section in do_deprovision_deployment
   to document the re-raised exception

All linting checks now pass.

Replace custom _generate_full_build_dockerfile implementation with
ZenML's internal PipelineDockerImageBuilder._generate_zenml_pipeline_dockerfile
method to:

- Eliminate code duplication
- Ensure consistency with how ZenML builds Docker images elsewhere
- Automatically benefit from future improvements to internal method
- Reduce maintenance burden

Changes:
- Import PipelineDockerImageBuilder and json module
- Modify _generate_full_build_dockerfile to call internal method
- Create requirements_files in format expected by internal method
- Merge environment/secrets into docker_settings.environment
- Internal method handles: FROM, WORKDIR, ENV, apt packages, requirements, COPY, USER
- Manually append ENTRYPOINT and CMD using json.dumps() for exec form
- Update docstring to document use of internal method

Benefits:
- ~50 lines of code eliminated
- Consistent with ZenML patterns (python_package_installer, installer_args, etc.)
- Proper handling of docker_settings.local_project_install_command
- Correct WORKDIR and permissions setup

Based on testing feedback, made the following critical fixes:

## Code Changes

1. **Fixed ENTRYPOINT/CMD Serialization (Line 217-218)**
   - Changed from str() to json.dumps() for proper Docker exec form
   - Before: str(entrypoint) → ['python', ...] (single quotes, invalid)
   - After: json.dumps(entrypoint) → ["python", ...] (double quotes, valid)
   - Fixes: "/bin/sh: 1: [python,: not found" error

2. **Fixed Default Port (Line 78, 107)**
   - Changed app_port default from 7860 to 8000
   - 7860 is HF Spaces default, but ZenML server runs on 8000
   - Updated both code and documentation

3. **Added Container Registry Requirement to Validator (Lines 102-140)**
   - Stack validator now requires container registry
   - Prevents deployment without pre-built image
   - Clear error message explains requirement

4. **Removed Full Build Mode (Lines 250-376 deleted)**
   - Deleted _generate_full_build_dockerfile method
   - Deleted _get_requirements_for_deployment method
   - Simplified do_provision_deployment to single mode
   - Removed unused imports (source_utils, PipelineDockerImageBuilder)
   - Full build mode caused issues:
     * Uploaded entire codebase (inefficient)
     * Configuration problems
     * Recommended to always use container registry

## Documentation Changes

1. **Updated Port Documentation**
   - Changed default from 7860 to 8000 in docs
   - Added note that 8000 is ZenML server default

2. **Removed Deployment Modes Section**
   - Deleted entire two-mode explanation
   - Simplified to single-mode operation

3. **Added Important Requirements Section**
   - Container Registry Requirement subsection
   - Explains why public access is needed
   - Lists recommended registries (Docker Hub, GHCR)
   - Example setup with GitHub Container Registry

4. **Added X-Frame-Options Configuration Section**
   - Documents iframe embedding issue
   - Provides complete code example
   - Shows DeploymentSettings with SecureHeadersConfig
   - Explains: xfo=False disables X-Frame-Options header
   - Without this, HF Spaces shows blank page

## Summary of Fixes

✅ ENTRYPOINT/CMD serialization (json.dumps)
✅ Default port 7860 → 8000
✅ Container registry now required by validator
✅ Full build mode removed
✅ Documentation updated with requirements
✅ X-Frame-Options configuration documented

These changes address all issues discovered during testing.

- Added link to https://huggingface.co/docs/hub/spaces-gpus for space_hardware setting
- Helps users understand available GPU options and pricing
- Addresses documentation feedback

Implements 8 improvements from code review:

1. Add organization support for deploying to HF organizations
   - Added 'organization' config parameter to HuggingFaceDeployerConfig
   - Updated _get_space_id() to check organization before falling back to username

2. Add space name length validation
   - Added HF_SPACE_NAME_MAX_LENGTH constant (96 chars)
   - Validate space name length and raise DeployerError if exceeded

3. Handle space visibility updates
   - Check if space_info.private != settings.private when updating
   - Call api.update_repo_visibility() to apply visibility changes

4. Fail on invalid hardware/storage instead of warning
   - Changed hardware/storage errors to raise DeploymentProvisionError
   - Added clear error messages with documentation links

5. Use proper error types for 404 detection
   - Import HfHubHTTPError from huggingface_hub.utils
   - Check e.response.status_code == 404 instead of string matching

6. Document timeout parameter in deprovision
   - Added docstring note that timeout is unused (deletion is immediate)

7. Remove unused space_exists variable
   - Removed space_exists assignments to fix lint error

8. Update documentation terminology
   - Changed "Docker applications" to "Docker Spaces" in deployers README

All changes maintain backward compatibility and improve code quality.

The secret_name parameter was redundant since token is already a SecretField
that supports ZenML's secret reference syntax ({{secret.key}}).

Changes:
- Removed secret_name from HuggingFaceDeployerConfig
- Simplified _get_token() to just return config.token or environment variable
- Updated validator to only check for token (not token or secret_name)
- Updated documentation to show proper secret reference syntax: {{hf_token.token}}
- Removed unused Client import (auto-removed by formatter)

This simplifies the API and follows ZenML's standard pattern for secret handling.

Added detailed descriptions to all config fields following ZenML standards:
- Minimum 30 characters
- Action-oriented language
- Concrete examples with realistic values
- Clear format specifications and constraints

Field descriptions added:
- token: Authentication, secret syntax, permissions, example
- organization: Purpose, example URL, permission requirements
- space_hardware: Options with specs, GPU tiers, documentation link
- space_storage: Tiers with sizes, persistence behavior
- space_prefix: Purpose, naming example, length constraint

All descriptions include practical examples and relevant documentation links
to help users configure the deployer correctly.

Changed the default value of `private` parameter from False to True to follow
security best practices. Private by default prevents accidental exposure of
deployment information.

Changes:
- Set private=True as default in HuggingFaceDeployerSettings
- Updated docstring to indicate default is True for security
- Updated documentation to reflect new default value
- Removed redundant private=True from code example (now default)
- Updated security section to mention both private and public Spaces
- Clarified that secure secrets handling protects credentials even in public Spaces

Users can still explicitly set private=False to make Spaces publicly visible,
but the safer default protects users who don't explicitly configure visibility.

Fixed lint error - DeploymentDeprovisionError was used but not imported.
This exception is used in do_deprovision_deployment when deletion fails.

CRITICAL BUG FIX: The deployer was returning the HuggingFace Space page URL
(https://huggingface.co/spaces/{space_id}) instead of the actual deployment
endpoint URL. This caused the base deployer to continuously poll because the
health check was hitting the HF page instead of the deployment server.

Changes:
- Extract the actual domain from runtime.raw['domains']
- Construct proper deployment URL: https://{domain}
- Only set URL when status is RUNNING (follows GCP/AWS pattern)
- URL is None for non-RUNNING states

Example:
- Before: https://huggingface.co/spaces/zenml/zenml-weather_agent-5917ffec
- After:  https://zenml-zenml-weather_agent-5917ffec.hf.space

This allows the base deployer's health check to succeed and stop polling
once the deployment is fully ready.

…PAytgCheWG1

Additional fix for continuous polling issue. The Space can be in RUNNING
stage (Docker container started) but the domain might not be ready yet
(DNS propagating, routing not configured). This caused premature RUNNING
status reports.

Changes:
- Only return DeploymentStatus.RUNNING when BOTH conditions are met:
  1. runtime.stage == SpaceStage.RUNNING
  2. domains[0]['stage'] == "READY"
- Space RUNNING + domain not ready → PENDING status
- Only set deployment URL when domain stage is READY
- Added domain_stage to metadata for debugging

This ensures health checks only run when the domain is actually ready
to receive traffic, not just when the Docker container has started.

Note: If polling continues after domain is READY, it likely means the
FastAPI app inside the container is still initializing. The base deployer
will continue polling until the /health endpoint responds with 200 OK.

Changed import from huggingface_hub.utils to huggingface_hub.errors
to fix mypy errors about implicit re-exports. HfHubHTTPError is
defined in the errors module and should be imported from there directly.

Added logging to show the deployment URL when the Space domain is READY.
This helps diagnose health check issues during polling by showing exactly
what URL the base deployer will attempt to connect to for health checks.

Fixed a critical bug where we were comparing runtime.stage (a string)
directly to SpaceStage enum objects, which always evaluated to False.
This caused deployments to never reach RUNNING status and continue
polling forever.

The HuggingFace API returns runtime.stage as a string (e.g., "RUNNING"),
so we must use enum.value for comparison (e.g., SpaceStage.RUNNING.value).

Changes:
- Use SpaceStage.RUNNING.value instead of SpaceStage.RUNNING
- Use enum.value for all stage comparisons
- Added comments explaining that runtime.stage is a string
- Maintains type safety by using enum values instead of hardcoded strings

This fixes the infinite polling issue where deployments would never
stop polling even when the Space was running and healthy.

Added detailed logging to diagnose two issues:

1. **Unknown status detection**: When the deployment status shows as
   "unknown", we now log the actual stage value received from HuggingFace
   and list all known stages. This helps identify if HuggingFace has
   introduced new stages we don't recognize yet.

2. **Health check failures**: Override _check_deployment_health with
   better logging to show:
   - The exact health check URL being tested
   - Whether health check passed or failed
   - Specific error messages when health check fails
   - Status codes returned from the endpoint

These logs will help diagnose why deployments continue polling even
when the Space appears to be running and the health endpoint is working.

The logs now show stage transitions and health check results at INFO
level for easier debugging without requiring DEBUG logging.

Fixed two critical issues discovered in deployment logs:

1. **Added RUNNING_APP_STARTING stage support**: HuggingFace introduced
   a new intermediate stage "RUNNING_APP_STARTING" that occurs when the
   container is running but the application inside is still starting up.
   Map this to PENDING status since the health endpoint isn't ready yet.

2. **Fixed DeploymentDefaultEndpoints import**: Corrected import path
   from `zenml.enums` to `zenml.config.deployment_settings` to fix
   ImportError that was preventing health checks from running.

These fixes allow deployments to properly transition through all HuggingFace
Space stages and reach RUNNING status once the app is fully started.

Fixed the issue where private HuggingFace Spaces would continuously poll
because the HTTP health check endpoint returns 404 for unauthenticated
requests.

Why this is the right solution:
1. Private Spaces block unauthenticated HTTP requests (returns 404)
2. We already have reliable health state from HuggingFace API
3. When Space stage is RUNNING and domain is READY, we know the
   deployment is genuinely healthy
4. HuggingFace platform handles internal health checks for us

The health check method now simply returns True, relying on the
comprehensive Space runtime state validation we perform in
do_get_deployment_state(). This allows deployments to complete
successfully for both public and private Spaces.

Cleaned up excessive logging that was added for debugging:
- Removed deployment URL log that printed on every poll
- Removed all debug logs showing space state details
- Simplified unknown stage warning message
- Removed health check debug log

Kept important informational logs:
- Creating/updating Space
- Restarting sleeping Spaces
- Unknown stage warnings (simplified)

This significantly reduces log verbosity while maintaining visibility
into key deployment lifecycle events.

Note: HTTP Request logs visible in output are from huggingface_hub
library's own logging, not from our deployer code.